Quick Summary

• Adds entity-keyed in-tick imperative physics ops to RapierClusterTickContext::physics: PhysicsHandle<'a>.
• Closes the gap in Rapier physics: in-tick imperative ops (impulses, forces, raycasts, joints, teleport) #121 — gameplay can now apply impulses/forces, teleport, raycast, run intersection queries, and create joints from inside on_tick.
• All ops are entity-keyed (take Uuid, never raw Rapier handles) and behave gracefully on missing ids and Fixed bodies.
• Lock-window restructure: state lock is held during on_tick for the Rapier-aware path so PhysicsHandle can mutate state synchronously. Plain ClusterSimulation keeps the legacy lock-released behavior.

Change Type

• feature

Impact

• User/developer impact: Implementers of RapierClusterSimulation can now do all the things local Rapier users can — explosions (radius query + apply_impulse), hitscan weapons (raycast), teleport/respawn (set_translation), joints between entities. The unified-entity invariant is preserved (no off-spine bodies; no raw Rapier handles in user code).
• Risk level: Low–medium. Internal lock-window change is the architecturally interesting piece, scoped to the Backend::Rapier path only. No replication / hot-path touches. All 76 prior rapier_cluster tests still pass after the restructure; 11 new tests cover the new ops.

Verification

• Build passes (cargo build -p arcane-infra and --features rapier-cluster)
• Tests pass (87/87 in arcane-infra::rapier_cluster — 76 prior + 11 new for Rapier physics: in-tick imperative ops (impulses, forces, raycasts, joints, teleport) #121)
• Doc examples compile (3/3 — including the new ActionGame imperative-ops example)
• Clippy clean both feature configs (cargo clippy --all-targets -- -D warnings)
• Formatter clean

Decisions made

• Lock held during user on_tick only for Backend::Rapier. Considered: hold lock for all backends.
  Reason: Plain ClusterSimulation (Backend::Cluster) has no PhysicsHandle to give it, so there's no functional reason to hold the lock during its on_tick. Keeps the legacy behavior of releasing the lock for plain sims and avoids any subtle change in lock contention for users who haven't migrated.

• pending_imperative_linvel: HashSet<Uuid> on RapierState (not on PhysicsHandle). Considered: store on PhysicsHandle, drain after on_tick.
  Reason: PhysicsHandle has lifetime 'a; storing the set on it would require either pub(crate) field access or an extraction method — both leak the lifecycle. Putting it on the underlying state is symmetric with pending_contact_events and avoids lifetime gymnastics.

• Track only set_linvel/apply_impulse, not set_translation/set_angvel/apply_force. Considered: track all imperative mutations.
  Reason: The spawn-loop sync only does set_linvel(entry.velocity). It doesn't touch translation, angvel, or forces. So only linvel needs the override-protection; the others compose naturally with the sync (apply_force adds during the step regardless of set_linvel; set_translation is read-only from the spawn loop).

• QueryPipeline constructed transiently per-query, not stored on RapierState. Considered: store + update once per step (matches the issue spec's wording "QueryPipeline integrated into RapierState, updated post-step").
  Reason: Rapier 0.32's QueryPipeline is QueryPipeline<'a> — a borrowed view bound to broad_phase + narrow_phase + bodies + colliders. It can no longer be a stored field. The BroadPhaseBvh::as_query_pipeline(...) factory builds it cheaply on demand. PhysicsHandle::raycast / intersections_with_shape construct it inline. Functionally equivalent to "post-step refreshed" — the broad_phase BVH is updated by physics_pipeline.step so all queries inside on_tick (which runs next tick, after the prior step) see the latest BVH.

• JointSpec carries axis as plain Vec3; normalized inside create_joint. Considered: take UnitVector / Unit<Vector>.
  Reason: Rapier 0.32 takes Vector directly for joint axes (auto-normalizes via the builder); user-facing API is simpler. We call to_rapier(axis).normalize() to defend against zero/non-unit input.

• JointId(ImpulseJointHandle) opaque newtype with private field. Considered: expose the Rapier handle directly via pub.
  Reason: Keeps the unified-entity invariant — user never holds a raw Rapier handle. JointId is Copy + Eq + Hash for ergonomic storage in user-side maps.

• #[non_exhaustive] on JointSpec variants and RaycastHit with pub const fn new(...) constructor on RaycastHit. Considered: skip the constructor.
  Reason: Same #[non_exhaustive] external-construction issue we hit in Rapier physics: per-entity body kind + material + collision filtering + sensor hooks #120 — can't construct via struct literal outside the crate. Constructor allows users to build RaycastHit instances in test fixtures / mock setups. JointSpec has no constructor needed since users always go through create_joint.

• Imperative ops on Fixed bodies silently no-op (return false). Considered: panic; or accept the op and let Rapier handle it.
  Reason: Per the issue's normalization spec — gameplay code shouldn't have to query body kind before applying force. Silent no-op + false return is the gentlest contract; matches the existing missing-entity behavior.

• Test fixture ScriptedSim<F> parameterized by closure. Considered: per-test struct (existing pattern from Rapier physics: per-entity body kind + material + collision filtering + sensor hooks #120).
  Reason: 11 Rapier physics: in-tick imperative ops (impulses, forces, raycasts, joints, teleport) #121 tests all need different in-tick behaviors. A closure-parameterized fixture (Fn(&mut PhysicsHandle, u64)) plus run_with_action helper drops boilerplate from ~15 lines per test to ~5. Per-test structs still used where the test needs richer state (joint despawn cleanup, Fixed-body sim).

Reference

• Issue: implements Rapier physics: in-tick imperative ops (impulses, forces, raycasts, joints, teleport) #121 (in-tick imperative physics ops)
• Builds on: Rapier physics: per-entity body kind + material + collision filtering + sensor hooks #120 (per-entity body kind / material / filtering / sensor — landed via feat(rapier-cluster): per-entity body kind / material / filtering / sensor hooks (#120) #125)
• Parent EPIC: Epic: Cluster physics backends — Unreal (Chaos) first, multi-engine path #8 — Cluster physics backends
• Inventory of Rapier gaps: Rapier physics: gap inventory — what's missing, what's blocked on which epic #122
• Downstream: Epic: Clustering visualization demo — probe-able, real-time view of cluster handoff and cross-cluster physics arcane-demos#6 (clustering visualization demo) needs apply_impulse + intersections_with_shape for explosions, raycast for shooting, set_translation for respawn
• Architecture doc: docs/architecture/entity-model.md